@phenix1024/editor 0.1.0 → 0.2.0

package/README.md

@@ -1,189 +1,284 @@
-# @ophx/editor
+# @phenix1024/editor
 
-## Установка
+Редактор документов для браузера на базе [Tiptap](https://tiptap.dev). Работает без фреймворков (подойдут React, Vue, Svelte, Angular или чистый JS), ему нужен только DOM-элемент. Документы сохраняются в переносимый архив `.ophx` (HTML + CSS + изображения в одном ZIP).
+
+- Заголовки, списки, отступы, таблицы, изображения с обтеканием, ссылки и цветные метки.
+- Markdown-подобный ввод: `# ` даёт заголовок, `- ` маркированный список, `1. ` нумерованный.
+- Готовая панель инструментов: стиль текста, поиск с подсветкой, содержание, отмена и повтор.
+- Режим просмотра, который запоминается между перезагрузками страницы.
+- Поля шаблонов: заполняемые места в документе, сбор значений, проверка обязательных полей.
 
-### npm + любой сборщик
+## Установка
 
 ```bash
 npm i @phenix1024/editor
 ```
 
+## Быстрый старт
+
+```html
+<div id="toolbar"></div>
+<div id="editor"></div>
+```
+
 ```ts
-import { OphxEditor, mountToolbar } from '@phenix1024/editor'
+import { OphxEditor } from '@phenix1024/editor'
 import '@phenix1024/editor/style.css'
 
 const editor = new OphxEditor({
-  element: document.querySelector('#editor')!,
-  content: '<h1>Документ</h1><p>Текст…</p>',
+  element: '#editor',   // элемент или CSS-селектор
+  toolbar: '#toolbar',  // необязательно: встроенная панель инструментов
+  content: '<h1>Документ</h1><p>Начните писать…</p>',
+  onUpdate: () => localStorage.setItem('draft', editor.getHTML()),
 })
+```
+
+Готово: редактор с панелью работает. Когда редактор больше не нужен, вызовите `editor.destroy()`. Он уберёт и панель.
+
+## Частые задачи
+
+### Получить и задать содержимое
 
-mountToolbar(document.querySelector('#toolbar')!, editor.editor)
+```ts
+const html = editor.getHTML()          // для автосохранения и отправки на сервер
+const json = editor.getJSON()          // структура документа Tiptap
+const text = editor.getText()          // простой текст
+
+editor.setContent('<p>Новый текст</p>')                    // onUpdate не вызывается
+editor.setContent('<p>Новый текст</p>', { emitUpdate: true })
+editor.clearContent()
 ```
 
-### Vue 3 + TypeScript
+### Режим просмотра
 
-```vue
-<script setup lang="ts">
-import { onMounted, onBeforeUnmount } from 'vue'
-import { OphxEditor, mountToolbar } from '@phenix1024/editor'
-import '@phenix1024/editor/style.css'
+```ts
+editor.setEditable(false)  // только чтение
+editor.setEditable(true)   // снова редактирование
+editor.isEditable          // текущий режим
+```
 
-let editor: OphxEditor | null = null
-let unmountToolbar: (() => void) | null = null
+Режим сохраняется в `localStorage` и восстанавливается после перезагрузки. В режиме просмотра панель отключает инструменты форматирования, а поиск и содержание остаются доступными.
 
-onMounted(() => {
-  editor = new OphxEditor({ element: document.querySelector('#editor')! })
-  unmountToolbar = mountToolbar(document.querySelector('#toolbar')!, editor.editor)
-})
+| Опция | Поведение |
+| --- | --- |
+| `editable: false` | Начальный режим, если сохранённого значения ещё нет. |
+| `editableStorageKey: 'my-key'` | Свой ключ `localStorage`, например отдельный для каждого документа. |
+| `editableStorageKey: null` | Не запоминать режим: всегда используется `editable`. |
+
+### Сохранить и открыть `.ophx`
 
-onBeforeUnmount(() => {
-  unmountToolbar?.()
-  editor?.destroy()
+```ts
+// Скачать файл в браузере
+await editor.downloadOphx({ filename: 'Договор', title: 'Договор поставки' })
+
+// Или получить Blob, например чтобы отправить на сервер
+const blob = await editor.saveOphx({ filename: 'Договор' })
+
+// Открыть файл, выбранный пользователем
+input.addEventListener('change', async () => {
+  const file = input.files?.[0]
+  if (!file) return
+  const doc = await editor.loadOphx(file)   // { title, filename, styles, css, html, ... }
+  console.log(doc.title)
 })
-</script>
 ```
 
-### CDN без сборщика
+После `loadOphx()` имя, заголовок и стили архива запоминаются. Следующий `saveOphx()` или `downloadOphx()` без параметров сохранит документ с теми же метаданными. Параметры, переданные явно, имеют приоритет.
 
-```html
-<link rel="stylesheet" href="https://unpkg.com/@phenix1024/editor@0.1.0/dist/ophx-editor.css">
-<script src="https://unpkg.com/@phenix1024/editor@0.1.0/dist/ophx-editor.iife.js"></script>
-<script>
-  const editor = new OphxEditor.OphxEditor({ element: document.querySelector('#editor') })
-  OphxEditor.mountToolbar(document.querySelector('#toolbar'), editor.editor)
-</script>
-```
+### Свои действия поверх Tiptap
 
-Аналогично для jsDelivr:
+`editor.editor` — это исходный экземпляр Tiptap `Editor`. Через него доступны все команды и события:
 
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phenix1024/editor@0.1.0/dist/ophx-editor.css">
-<script src="https://cdn.jsdelivr.net/npm/@phenix1024/editor@0.1.0/dist/ophx-editor.iife.js"></script>
+```ts
+editor.editor.chain().focus().toggleBold().run()
+editor.editor.on('selectionUpdate', () => { /* ... */ })
 ```
 
-> Для CDN лучше жёстко фиксировать версию, чтобы обновления не ломали существующий код.
+Дополнительные расширения Tiptap передаются через `extensions: [...]`.
 
-Переносимый WYSIWYM-редактор на Tiptap. Ядро не зависит от React, Vue, Svelte или другого UI-фреймворка: ему нужен только DOM-контейнер. Панель инструментов опциональна — можно использовать готовую `mountToolbar()` или построить собственный интерфейс поверх публичного Tiptap instance.
+### Загрузка изображений на сервер
 
-## Возможности
+По умолчанию панель вставляет изображения как `data:` URL, а при сохранении они упаковываются в `.ophx`. Чтобы загружать их на свой сервер:
 
-- Заголовки H1–H6, абзацы, маркированные и нумерованные списки; стандартные markdown/input rules Tiptap преобразуют `# `, `- ` и `1. ` при вводе.
-- Жирный, курсив, подчёркивание, зачёркивание, ссылки и метки.
-- Списки, отступы для абзацев/заголовков, изображения, таблицы и сворачивание разделов по заголовкам.
-- Содержание с переходом к заголовку, поиск с подсветкой, Undo/Redo.
-- Не допускается повторный пробел при обычном вводе; Enter не создаёт последовательные пустые строки. Проверка орфографии использует браузерную проверку (`spellcheck`) и язык `ru`.
-- Обычные клавиатурные команды редактора и браузера: выделение, копирование/вставка, Home/End, Undo/Redo и др.
-- Импорт/экспорт `.ophx` v2: плоский ZIP с HTML-файлом, stylesheet-файлами и изображениями.
-- Поля шаблонов Ophx: сохранение `contenteditable`, редактирование полей `.ophx-field`, сбор значений и проверка обязательных полей.
+```ts
+const editor = new OphxEditor({
+  element: '#editor',
+  toolbar: '#toolbar',
+  toolbarOptions: {
+    onInsertImage: async (file) => {
+      const url = await uploadToServer(file)
+      editor.editor.chain().focus().setImage({ src: url, alt: file.name }).run()
+    },
+  },
+})
+```
 
-Проверка орфографии зависит от браузера и установленных словарей. Для удалённых изображений, недоступных из-за CORS, сохраняется исходная внешняя ссылка; локальные/вставленные изображения упаковываются в корень архива.
+### Метки
 
-## Разработка
+Выделите текст и нажмите «Метка» на панели. Во всплывающем окне введите название или выберите существующее. Клик по метке показывает её название, а в режиме редактирования там же её можно изменить или удалить. Метки сохраняются как `<mark data-label="...">`. Метки «важно» и «идея» имеют свои цвета, цвета остальных задаются в CSS:
 
-```sh
-npm install
-npm run dev
-npm run typecheck
-npm run build
+```css
+.ophx-editor-surface mark[data-label="срочно"] { background: #ffe0b3; }
 ```
 
-`npm run build` собирает демо в `dist-demo/` и библиотеку/standalone-бандлы в `dist/`.
+### Поля шаблонов
 
-## Подключение без фреймворка
+Поле — это элемент с классом `ophx-field`, атрибутом `contenteditable="true"` и уникальным `data-ophx-field`:
 
-```ts
-import { OphxEditor, mountToolbar } from '@ophx/editor'
-import '@ophx/editor/style.css'
+```html
+<p>Покупатель: <span class="ophx-field" contenteditable="true"
+   data-ophx-field="buyer" data-ophx-label="Покупатель" data-ophx-required="true"></span></p>
+```
 
-const editor = new OphxEditor({
-  element: document.querySelector('#editor')!,
-  content: '<h1>Документ</h1><p>Текст…</p>',
-  onUpdate: ({ editor }) => autosave(editor.getHTML()),
-})
-const unmountToolbar = mountToolbar(document.querySelector('#toolbar')!, editor.editor)
+```ts
+editor.getFields()                 // [{ id, label, required, value }]
+editor.getMissingRequiredFields()  // незаполненные обязательные поля
 
-// При размонтировании host:
-unmountToolbar()
-editor.destroy()
+import { convertUnderscoresToFields } from '@phenix1024/editor'
+const { html } = convertUnderscoresToFields('<p>ФИО: ______</p>')  // «___» превращается в поля f1, f2, …
 ```
 
-## Подключение в React
+Фрагменты с `contenteditable="false"` сохраняются и остаются нередактируемыми.
+
+## Фреймворки
+
+### React
 
 ```tsx
 import { useEffect, useRef } from 'react'
-import { OphxEditor, mountToolbar } from '@ophx/editor'
-import '@ophx/editor/style.css'
+import { OphxEditor } from '@phenix1024/editor'
+import '@phenix1024/editor/style.css'
 
-export function DocumentEditor() {
-  const editorHost = useRef<HTMLDivElement>(null)
-  const toolbarHost = useRef<HTMLDivElement>(null)
+export function DocumentEditor({ initialHtml }: { initialHtml?: string }) {
+  const editorRef = useRef<HTMLDivElement>(null)
+  const toolbarRef = useRef<HTMLDivElement>(null)
 
   useEffect(() => {
-    if (!editorHost.current || !toolbarHost.current) return
-    const editor = new OphxEditor({ element: editorHost.current })
-    const unmountToolbar = mountToolbar(toolbarHost.current, editor.editor)
-    return () => { unmountToolbar(); editor.destroy() }
+    const editor = new OphxEditor({
+      element: editorRef.current!,
+      toolbar: toolbarRef.current!,
+      content: initialHtml,
+    })
+    return () => editor.destroy()
   }, [])
 
-  return <><div ref={toolbarHost} /><div ref={editorHost} /></>
+  return (
+    <>
+      <div ref={toolbarRef} />
+      <div ref={editorRef} />
+    </>
+  )
 }
 ```
 
-Для Vue/Svelte/Angular используется тот же DOM API в `onMounted`/`onMount`/lifecycle хуке. Не подключайте одновременно встроенный и собственный toolbar.
+### Vue 3
 
-## Формат `.ophx`
+```vue
+<script setup lang="ts">
+import { onMounted, onBeforeUnmount, ref } from 'vue'
+import { OphxEditor } from '@phenix1024/editor'
+import '@phenix1024/editor/style.css'
 
-`.ophx` соответствует v2 спецификации: это обычный ZIP без шифрования и ZIP64; записи создаются с DEFLATE, имена кодируются в UTF-8. Все файлы лежат плоским списком в корне. Внутри должен быть ровно один HTML-файл, его имя совпадает с именем внешнего `.ophx` без расширения. Стили и изображения тоже лежат в корне, без каталогов:
+const editorEl = ref<HTMLElement>()
+const toolbarEl = ref<HTMLElement>()
+let editor: OphxEditor | undefined
 
-```text
-Договор.ophx
-├── Договор.html
-├── default.css
-└── image-1.png
+onMounted(() => {
+  editor = new OphxEditor({ element: editorEl.value!, toolbar: toolbarEl.value! })
+})
+onBeforeUnmount(() => editor?.destroy())
+</script>
+
+<template>
+  <div ref="toolbarEl" />
+  <div ref="editorEl" />
+</template>
 ```
 
-```ts
-import { exportOphx, importOphx, downloadBlob } from '@phenix1024/editor'
+Не храните экземпляр `OphxEditor` в `ref()` или `reactive()`: прокси Vue мешают работе Tiptap.
 
-const archive = await exportOphx(editor.getHTML(), {
-  filename: 'Договор', // basename должен совпадать с именем скачиваемого .ophx
-  title: 'Договор поставки',
-  styles: { 'default.css': cssText },
-  bodyContentEditable: 'false', // если архив был импортирован с таким атрибутом
-})
-downloadBlob(archive, 'Договор.ophx')
-
-const document = await importOphx(file)
-editor.setContent(document.html)
-const updatedArchive = await exportOphx(editor.getHTML(), {
-  filename: document.filename,
-  title: document.title,
-  styles: document.styles,
-  bodyContentEditable: document.bodyContentEditable,
-})
-downloadBlob(updatedArchive, `${document.filename}.ophx`)
-// document.styles содержит все подключённые локальные CSS-файлы.
-// document.css — удобный алиас первого stylesheet.
+### Без сборщика (CDN)
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@phenix1024/editor@0.2.0/dist/ophx-editor.css">
+<script src="https://unpkg.com/@phenix1024/editor@0.2.0/dist/ophx-editor.iife.js"></script>
+
+<div id="toolbar"></div>
+<div id="editor"></div>
+<script>
+  const editor = new OphxEditor.OphxEditor({ element: '#editor', toolbar: '#toolbar' })
+</script>
 ```
 
-Имена в `styles` и `assets` — простые имена файлов, без путей. Изображения с локальными именами можно передать в `assets`; вставленные в редактор `data:image` и `blob:` изображения автоматически превращаются в `image-<номер>.<ext>`. Внешние `http(s)` и `data:` ссылки сохраняются как внешние.
+Через jsDelivr: `https://cdn.jsdelivr.net/npm/@phenix1024/editor@0.2.0/dist/...`. Версию в ссылке лучше фиксировать.
 
-Импорт принимает только ZIP v2 с одним корневым `.html`; старые не-ZIP/XML варианты определяются как неподдерживаемые. Локальные ссылки на CSS и изображения проверяются по точным именам. Скриптовые элементы и event-handler атрибуты удаляются перед передачей HTML редактору. Содержимое `styles` возвращается вызывающему приложению — оно может применить CSS в изолированном контейнере или iframe.
+## API
 
-### Поля шаблона
+### `new OphxEditor(options)`
+
+| Опция | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `element` | `HTMLElement \| string` | — | Контейнер документа (обязательно). |
+| `toolbar` | `HTMLElement \| string` | — | Контейнер встроенной панели инструментов. |
+| `toolbarOptions` | `{ onInsertImage?(file) }` | — | Настройки панели. |
+| `content` | `string \| JSON` | `'<p></p>'` | Начальное содержимое. |
+| `placeholder` | `string` | `'Начните писать…'` | Подсказка в пустом документе. |
+| `editable` | `boolean` | `true` | Начальный режим, если нет сохранённого. |
+| `editableStorageKey` | `string \| null` | `'ophx-editor-editable'` | Ключ `localStorage` для режима; `null` отключает хранение. |
+| `onUpdate` | `({ editor }) => void` | — | Вызывается при каждом изменении документа. |
+| `extensions` | `Extension[]` | `[]` | Дополнительные расширения Tiptap. |
+
+### Методы и свойства
+
+| | |
+| --- | --- |
+| `getHTML()`, `getJSON()`, `getText()` | Содержимое документа. |
+| `setContent(content, { emitUpdate? })`, `clearContent()` | Замена содержимого. |
+| `setEditable(bool)`, `isEditable` | Режим редактирования или просмотра. |
+| `isEmpty` | Пустой ли документ. |
+| `focus(pos?)`, `blur()` | Фокус: `'start'`, `'end'`, `'all'` или позиция. |
+| `undo()`, `redo()`, `canUndo()`, `canRedo()` | История изменений. |
+| `setSearchQuery(query)` | Подсветка найденного текста. |
+| `loadOphx(file)` | Открыть `.ophx`, возвращает `OphxDocument`. |
+| `saveOphx(options?)` | Создать `.ophx` и вернуть `Blob`. |
+| `downloadOphx(options?)` | Скачать `.ophx`. |
+| `getFields()`, `getMissingRequiredFields()` | Поля шаблона. |
+| `destroy()` | Удалить редактор и панель. |
+| `editor` | Исходный Tiptap `Editor`. |
+
+Параметры сохранения (`OphxExportOptions`): `filename` (имя без `.ophx`), `title`, `styles` (`{ 'имя.css': 'css…' }`), `assets` (файлы изображений по имени), `bodyContentEditable`.
+
+### Другие экспорты
+
+- `mountToolbar(host, tiptapEditor, options?)` — смонтировать панель вручную. Возвращает функцию очистки.
+- `exportOphx(html, options)`, `importOphx(file)`, `downloadBlob(blob, filename)` — работа с архивами без редактора.
+- `convertUnderscoresToFields(html, prefix?)` — превращает `___` в поля шаблона.
+- Расширения Tiptap: `Label`, `CollapsibleHeading`, `Indentation`, `OphxInlineField`, `OphxBlockField`, `OphxReadonlyBlock`, `OphxReadonlyInline`, `OphxEditability`, `TextSearch`, `WysiwymRules`.
 
-В документе сохраняются поля `span` (inline) и `p`/`div` (block) с `.ophx-field`, `contenteditable="true"` и уникальным `data-ophx-field`. Статические фрагменты с `contenteditable="false"` сохраняются; при `body contenteditable="false"` это состояние также переносится в editor-модель. Значения доступны через `editor.getFields()`, обязательные незаполненные поля — через `editor.getMissingRequiredFields()`.
+## Формат `.ophx`
 
-Для подготовки шаблона helper `convertUnderscoresToFields(html)` заменяет каждую последовательность `_{2,}` в текстовых узлах отдельным пустым полем с ключами `f1`, `f2`, …; кодовые блоки и нередактируемые участки пропускаются.
+Обычный ZIP, все файлы лежат в корне. Внутри ровно один HTML, его имя совпадает с именем архива. Рядом лежат CSS и изображения:
 
-## API
+```text
+Договор.ophx
+├── Договор.html
+├── default.css
+└── image-1.png
+```
+
+- Вставленные изображения (`data:`, `blob:`) упаковываются как `image-<n>.<ext>`. Внешние `http(s)` ссылки остаются ссылками.
+- При открытии из HTML удаляются `<script>` и обработчики событий (`on*`).
+- CSS из архива возвращается в `doc.styles` и к странице автоматически не применяется. Где его применять, решает приложение.
+
+## Разработка
+
+```sh
+npm install
+npm run dev        # демо на http://localhost:5173
+npm run typecheck
+npm run build      # демо в dist-demo/, библиотека в dist/
+```
 
-- `new OphxEditor({ element, content?, placeholder?, editable?, onUpdate?, extensions? })`
-- `editor.editor` — исходный Tiptap `Editor` для команд и подписок.
-- `getHTML()`, `getJSON()`, `setContent(content)`, `setSearchQuery(query)`, `destroy()`.
-- `mountToolbar(host, editor, { onInsertImage? })` возвращает функцию очистки.
-- `exportOphx(html, { filename, title?, styles?, assets?, bodyContentEditable? })`, `importOphx(file)`, `downloadBlob(blob, filename)`.
-- `getFields()` и `getMissingRequiredFields()` возвращают валидные уникальные поля шаблона.
-- `convertUnderscoresToFields(html, prefix?)` возвращает преобразованный HTML, число полей и их IDs.
+## Лицензия
 
-Интеграционный пакет поставляет Tiptap extensions и JSZip как runtime-зависимости. Подключайте stylesheet явно в приложении, где сборщик не обрабатывает CSS imports автоматически.
+MIT